<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Device::Gsm - Perl extension to interface GSM phones / modems</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:cosimo@cpan.org" />
</head>

<body style="background-color: white">

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

	<li><a href="#name">NAME</a></li>
	<li><a href="#synopsis">SYNOPSIS</a></li>
	<li><a href="#description">DESCRIPTION</a></li>
	<li><a href="#methods">METHODS</a></li>
	<ul>

		<li><a href="#connect__"><code>connect()</code></a></li>
		<li><a href="#datetime__"><code>datetime()</code></a></li>
		<li><a href="#delete_sms__"><code>delete_sms()</code></a></li>
		<li><a href="#hangup__"><code>hangup()</code></a></li>
		<li><a href="#imei__"><code>imei()</code></a></li>
		<li><a href="#manufacturer__"><code>manufacturer()</code></a></li>
		<li><a href="#messages__"><code>messages()</code></a></li>
		<li><a href="#mode__"><code>mode()</code></a></li>
		<li><a href="#model__"><code>model()</code></a></li>
		<li><a href="#network__"><code>network()</code></a></li>
		<li><a href="#signal_quality__"><code>signal_quality()</code></a></li>
		<li><a href="#software_version__"><code>software_version()</code></a></li>
		<li><a href="#storage__"><code>storage()</code></a></li>
		<li><a href="#test_command__"><code>test_command()</code></a></li>
		<li><a href="#register__"><code>register()</code></a></li>
		<li><a href="#send_sms__"><code>send_sms()</code></a></li>
		<li><a href="#service_center__"><code>service_center()</code></a></li>
	</ul>

	<li><a href="#requires">REQUIRES</a></li>
	<li><a href="#export">EXPORT</a></li>
	<li><a href="#troubleshooting">TROUBLESHOOTING</a></li>
	<li><a href="#todo">TO-DO</a></li>
	<li><a href="#author">AUTHOR</a></li>
	<li><a href="#see_also">SEE ALSO</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Device::Gsm - Perl extension to interface GSM phones / modems</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
  use Device::Gsm;</pre>
<pre>
  my $gsm = new Device::Gsm( port =&gt; '/dev/ttyS1', pin =&gt; 'xxxx' );</pre>
<pre>
  if( $gsm-&gt;connect() ) {
      print &quot;connected!\n&quot;;
  } else {
      print &quot;sorry, no connection with gsm phone on serial port!\n&quot;;
  }</pre>
<pre>
  # Register to GSM network (you must supply PIN number in above new() call)
  $gsm-&gt;register();</pre>
<pre>
  # Send quickly a short text message
  $gsm-&gt;send_sms(
      recipient =&gt; '+3934910203040',
      content   =&gt; 'Hello world! from Device::Gsm'
  );</pre>
<pre>
  # Get list of Device::Gsm::Sms message objects
  # see `examples/read_messages.pl' for all the details
  my @messages = $gsm-&gt;messages();</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p><code>Device::Gsm</code> class implements basic GSM functions, network registration and SMS sending.</p>
<p>This class supports also <code>PDU</code> mode to send <code>SMS</code> messages, and should be
fairly usable. In the past, I have developed and tested it under Linux RedHat 7.1
with a 16550 serial port and Siemens C35i/C45 GSM phones attached with
a Siemens-compatible serial cable. Currently, I'm developing and testing this stuff
with Linux Slackware 10.2 and a <strong>Cambridge Silicon Radio</strong> (CSR) USB
bluetooth dongle, connecting to a Nokia 6600 phone.</p>
<p>Please be kind to the universe and contact me if you have troubles or you are
interested in this.</p>
<p>Please be monstruosly kind to the universe and (if you don't mind spending an SMS)
use the <code>examples/send_to_cosimo.pl</code> script to make me know that Device::Gsm works
with your device (thanks!).</p>
<p>Recent versions of <code>Device::Gsm</code> have also an utility called <code>autoscan</code> in
the <code>bin/</code> folder, that creates a little profile of the devices it runs
against, that contains information about supported commands and exact output
of commands to help recognize similar devices.</p>
<p>Be sure to send me your profile by email (if you want to),
so I can add better support for your device in the future!</p>
<p>
</p>
<hr />
<h1><a name="methods">METHODS</a></h1>
<p>The following documents all supported methods with simple examples of usage.</p>
<p>
</p>
<h2><a name="connect__"><code>connect()</code></a></h2>
<p>This is the main call that connects to the appropriate device. After the
connection has been established, you can start issuing commands.
The list of accepted parameters (to be specified as hash keys and values) is
the same of <code>Device::SerialPort</code> (or <code>Win32::SerialPort</code> on Windows platform),
as all parameters are passed to those classes' <code>connect()</code> method.</p>
<p>The default value for <code>baudrate</code> parameter is <code>19200</code>.</p>
<p>Example:</p>
<pre>
        my $gsm = Device::Gsm-&gt;new( port=&gt;'/dev/ttyS0', log=&gt;'syslog' );
        # ...
        if( $gsm-&gt;connect(baudrate =&gt; 19200) ) {
                print &quot;Connected!&quot;;
        } else {
                print &quot;Could not connect, sorry!&quot;;
        }
        # ...</pre>
<p>
</p>
<h2><a name="datetime__"><code>datetime()</code></a></h2>
<p>Used to get or set your phone/gsm modem date and time.</p>
<p>If called without parameters, it gets the current phone/gsm date and time in ``gsm''
format ``YY/MM/DD,HH:MN:SS''. For example <code>03/12/15,22:48:59</code> means December the 15th,
at 10:48:59 PM. Example:</p>
<pre>
        $datestr = $gsm-&gt;datetime();</pre>
<p>If called with parameters, sets the current phone/gsm date and time to that
of supplied value. Example:</p>
<pre>
        $newdate = $gsm-&gt;datetime( time() );</pre>
<p>where <code>time()</code> is the perl's builtin <code>time()</code> function (see <code>perldoc -f time</code> for details).
Another variant allows to pass a <code>localtime</code> array to set the correspondent datetime. Example:</p>
<pre>
        $newdate = $gsm-&gt;datetime( localtime() );</pre>
<p>(Note the list context). Again you can read the details for <code>localtime</code> function
with <code>perldoc -f localtime</code>.</p>
<p>If your device does not support this command, an <strong>undefined</strong> value will be returned
in either case.</p>
<p>
</p>
<h2><a name="delete_sms__"><code>delete_sms()</code></a></h2>
<p>This method deletes a message from your SIM card, given the message index number.
Example:</p>
<pre>
    $gsm-&gt;delete_sms(3);</pre>
<p>An optional second parameter specifies the ``storage''. It allows to delete messages
from gsm phone memory or sim card memory. Example:</p>
<pre>
    # Deletes first message from gsm phone memory
    $gsm-&gt;delete_sms(1, 'ME');</pre>
<pre>
    # Deletes 3rd message from sim card
    $gsm-&gt;delete_sms(3, 'SM');</pre>
<p>By default, it uses the currently set storage, via the <code>storage()</code> method.</p>
<p>
</p>
<h2><a name="hangup__"><code>hangup()</code></a></h2>
<p>Hangs up the phone, terminating the active calls, if any.
This method has been never tested on real ``live'' conditions, but it needs to be
specialized for GSM phones, because it relies on <code>+HUP</code> GSM command.
Example:</p>
<pre>
        $gsm-&gt;hangup();</pre>
<p>
</p>
<h2><a name="imei__"><code>imei()</code></a></h2>
<p>Returns the device own IMEI number (International Mobile Equipment Identifier ???).
This identifier is numeric and should be unique among all GSM mobile devices and phones.
This is not really true, but ... . Example:</p>
<pre>
        my $imei = $gsm-&gt;imei();</pre>
<p>
</p>
<h2><a name="manufacturer__"><code>manufacturer()</code></a></h2>
<p>Returns the device manufacturer, usually only the first word (example: <code>Nokia</code>,
<code>Siemens</code>, <code>Falcom</code>, ...). Example:</p>
<pre>
        my $man_name = $gsm-&gt;manufacturer();
        if( $man_name eq 'Nokia' ) {
                print &quot;We have a nokia phone...&quot;;
        } else {
                print &quot;We have a $man_name phone...&quot;;
        }</pre>
<p>
</p>
<h2><a name="messages__"><code>messages()</code></a></h2>
<p>This method is a somewhat unstable and subject to change, but for now it seems to work.
It is meant to extract all text SMS messages stored on your SIM card or gsm phone.
In list context, it returns a list of messages (or undefined value if no message or errors),
every message being a <code>Device::Gsm::Sms</code> object.</p>
<p>The only parameter specifies the <code>storage</code> where you want to read the messages,
and can assume some of the following values (but check your phone/modem manual for
special manufacturer values):</p>
<dl>
<dt><strong><a name="item_me"><code>ME</code></a></strong>

<dd>
<p>Means gsm phone <strong>ME</strong>mory</p>
</dd>
</li>
<dt><strong><a name="item_mt"><code>MT</code></a></strong>

<dd>
<p>Means gsm phone <strong>ME</strong>mory on Nokia phones?</p>
</dd>
</li>
<dt><strong><a name="item_sm"><code>SM</code></a></strong>

<dd>
<p>Means <strong>S</strong>im card <strong>M</strong>emory (default value)</p>
</dd>
</li>
</dl>
<p>Example:</p>
<pre>
    my $gsm = Device::Gsm-&gt;new();
    $gsm-&gt;connect(port=&gt;'/dev/ttyS0') or die &quot;Can't connect!&quot;;</pre>
<pre>
    for( $gsm-&gt;messages('SM') )
    {
        print $_-&gt;sender(), ': ', $_-&gt;content(), &quot;\n&quot;;
    }</pre>
<p>
</p>
<h2><a name="mode__"><a href="#item_mode"><code>mode()</code></a></a></h2>
<p>Sets the device GSM command mode. Accepts one parameter to set the new mode that can
be the string <code>text</code> or <code>pdu</code>. Example:</p>
<pre>
        # Set text mode
    $gsm-&gt;mode('text');
    
    # Set pdu mode
    $gsm-&gt;mode('pdu');</pre>
<p>
</p>
<h2><a name="model__"><code>model()</code></a></h2>
<p>Returns phone/device model name or number. Example:</p>
<pre>
        my $model = $gsm-&gt;model();</pre>
<p>For example, for Siemens C45, <code>$model</code> holds <code>C45</code>; for Nokia 6600, <code>$model</code>
holds <code>6600</code>.</p>
<p>
</p>
<h2><a name="network__"><code>network()</code></a></h2>
<p>Returns the current registered or preferred GSM network operator. Example:</p>
<pre>
        my $net_name = $gsm-&gt;network();
    # Returns 'Wind Telecom Spa'</pre>
<pre>
    my($net_name, $net_code) = $gsm-&gt;network();
    # Returns ('Wind Telecom Spa', '222 88')</pre>
<p>This obviously varies depending on country and network operator. For me now,
it holds ``Wind Telecomunicazioni SpA''. It is not guaranteed that the mobile
phone returns the decoded network name. It can also return a gsm network code,
like <code>222 88</code>. In this case, an attempt to decode the network name is made.</p>
<p>Be sure to call the <code>network()</code> method when already registered to gsm
network. See <code>register()</code> method.</p>
<p>
</p>
<h2><a name="signal_quality__"><code>signal_quality()</code></a></h2>
<p>Returns the measure of signal quality expressed in dBm units, where near to zero is better.
An example value is -91 dBm, and reported value is <code>-91</code>. Values should range from
-113 to -51 dBm, where -113 is the minimum signal quality and -51 is the theorical maximum quality.</p>
<pre>
        my $level = $gsm-&gt;signal_quality();</pre>
<p>If signal quality can't be read or your device does not support this command,
an <strong>undefined</strong> value will be returned.</p>
<p>
</p>
<h2><a name="software_version__"><code>software_version()</code></a></h2>
<p>Returns the device firmare version, as stored by the manufacturer. Example:</p>
<pre>
        my $rev = $gsm-&gt;software_revision();</pre>
<p>For example, for my Siemens C45, <code>$rev</code> holds <code>06</code>.</p>
<p>
</p>
<h2><a name="storage__"><code>storage()</code></a></h2>
<p>Allows to get/set the current sms storage, that is where the sms messages are saved,
either the sim card or gsm phone memory. Phones/modems that do not support this feature
(implemented by <code>+CPMS</code> AT command won't be affected by this method.</p>
<pre>
    my @msg;
        my $storage = $gsm-&gt;storage();
    print &quot;Current storage is $storage\n&quot;;</pre>
<pre>
    # Read all messages on sim card
    $gsm-&gt;storage('SM');
    @msg = $gsm-&gt;messages();</pre>
<pre>
    # Read messages from gsm phone memory
    $gsm-&gt;storage('ME');
    push @msg, $gsm-&gt;messages();</pre>
<p>
</p>
<h2><a name="test_command__"><code>test_command()</code></a></h2>
<p>This method allows to query the device to know if a specific AT GSM command is supported.
This is used only with GSM commands (those with <code>AT+</code> prefix).
For example, I want to know if my device supports the <code>AT+GXXX</code> command.
All we have to do is:</p>
<pre>
        my $gsm = Device::Gsm-&gt;new( port =&gt; '/dev/myport' );</pre>
<pre>
        ...</pre>
<pre>
        if( $gsm-&gt;test_command('GXXX') ) {
                # Ok, command is supported
        } else {
                # Nope, no GXXX command
        }</pre>
<p>Note that if you omit the starting <code>+</code> character, it is automatically added.
You can also test commands like <code>^SNBR</code> or the like, without <code>+</code> char being added.</p>
<I>Must be explained better, uh?</I><p>
</p>
<h2><a name="register__"><code>register()</code></a></h2>
<p>``Registering'' on the GSM network is what happens when you turn on your mobile phone or GSM equipment
and the device tries to reach the GSM operator network. If your device requires a <strong>PIN</strong> number,
it is used here (but remember to supply the <code>pin</code> parameter in <code>new()</code> object constructor for this
to work.</p>
<p>Registration can take some seconds, don't worry for the wait.
After that, you are ready to send your SMS messages or do some voice calls, ... .
Normally you don't need to call <code>register()</code> explicitly because it is done automatically for you
when/if needed.</p>
<p>If return value is true, registration was successful, otherwise there is something wrong;
probably you supplied the wrong PIN code or network unreachable.</p>
<p>
</p>
<h2><a name="send_sms__"><code>send_sms()</code></a></h2>
<p>Obviously, this sends out SMS text messages. I should warn you that <strong>you cannot send</strong>
(for now) MMS, ringtone, smart, ota messages of any kind with this method.</p>
<p>Send out an SMS message quickly:</p>
<pre>
        my $sent = $gsm-&gt;send_sms(
                content   =&gt; 'Hello, world!',   # SMS text
                recipient =&gt; '+99000123456',    # recipient phone number
        );</pre>
<pre>
        if( $sent ) {
                print &quot;OK!&quot;;
        } else {
                print &quot;Troubles...&quot;;
        }</pre>
<p>The allowed parameters to <code>send_sms()</code> are:</p>
<dl>
<dt><strong><a name="item_class"><code>class</code></a></strong>

<dd>
<p>Class parameter can assume two values: <code>normal</code> and <code>flash</code>. Flash (or class zero) messages are
particular because they are immediately displayed (without user confirm) and never stored
on phone memory, while <code>normal</code> is the default.</p>
</dd>
</li>
<dt><strong><a name="item_content"><code>content</code></a></strong>

<dd>
<p>This is the text you want to send, consisting of max 160 chars if you use <strong>PDU</strong> mode
and 140 (?) if in <strong>text</strong> mode (more on this later).</p>
</dd>
</li>
<dt><strong><a name="item_mode"><code>mode</code></a></strong>

<dd>
<p>Can assume two values (case insensitive): <code>pdu</code> and <code>text</code>.
<code>PDU</code> means <strong>Protocol Data Unit</strong> and it is a sort of <strong>binary</strong> encoding of commands,
to save time/space, while <code>text</code> is the normal GSM commands text mode.</p>
</dd>
<dd>
<p>Recent mobile phones and GSM equipments surely have support for <code>PDU</code> mode.
Older OEM modules (like Falcom Swing, for example) don't have PDU mode, but only text mode.
It is just a matter of trying.</p>
</dd>
</li>
<dt><strong><a name="item_recipient"><code>recipient</code></a></strong>

<dd>
<p>Phone number of message recipient</p>
</dd>
</li>
<dt><strong><a name="item_status_report"><code>status_report</code></a></strong>

<dd>
<p>If present with a true value, it enables sending of SMS messages (only for PDU mode,
text mode SMS won't be influenced by this parameter) with the status report,
also known as delivery report, that is a short message that reports the status
of your sent message.
Usually this is only available if your mobile company supports this feature,
and probably you will be charged a small amount for this service.</p>
</dd>
<dd>
<p>More information on this would be welcome.</p>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="service_center__"><code>service_center()</code></a></h2>
<p>If called without parameters, returns the actual SMS Service Center phone number. This is
the number your phone automatically calls when receiving and sending SMS text messages, and
your network operator should tell you what this number is.</p>
<p>Example:</p>
<pre>
        my $gsm = Device::Gsm-&gt;new( port =&gt; 'COM1' );
        $gsm-&gt;connect() or die &quot;Can't connect&quot;;
        $srv_cnt = $gsm-&gt;service_center();
        print &quot;My service center number is: $srv_cnt\n&quot;;</pre>
<p>If you want to set or change this number (if used improperly this can disable
sending of SMS messages, so be warned!), you can try something like:</p>
<pre>
        my $ok = $gsm-&gt;service_center('+99001234567');
        print &quot;Service center changed!\n&quot; if $ok;</pre>
<p>
</p>
<hr />
<h1><a name="requires">REQUIRES</a></h1>
<ul>
<li>
<p>Device::Modem, which in turn requires</p>
</li>
<li>
<p>Device::SerialPort (or Win32::SerialPort on Windows machines)</p>
</li>
</ul>
<p>
</p>
<hr />
<h1><a name="export">EXPORT</a></h1>
<p>None</p>
<p>
</p>
<hr />
<h1><a name="troubleshooting">TROUBLESHOOTING</a></h1>
<p>If you experience problems, please double check:</p>
<dl>
<dt><strong><a name="item_device_permissions">Device permissions</a></strong>

<dd>
<p>Maybe you don't have necessary permissions to access your serial,
irda or bluetooth port device. Try executing your script as root, or
try, if you don't mind, <code>chmod a+rw /dev/ttyS1</code> (or whatever device
you use instead of <code>/dev/ttyS1</code>).</p>
</dd>
</li>
<dt><strong><a name="item_connection_speed">Connection speed</a></strong>

<dd>
<p>Try switching <code>baudrate</code> parameter from 19200 (the default value)
to 9600 or viceversa. This one is the responsible of 80% of the problems,
because there is no baudrate auto-detection.</p>
</dd>
</li>
<dt><strong><a name="item_device_autoscan">Device autoscan</a></strong>

<dd>
<p>If all else fails, please use the <strong>autoscan</strong> utility in the <code>bin/</code> folder
of the <code>Device::Gsm</code> distribution. Try running this autoscan utility and
examine the log file produced in the current directory.</p>
</dd>
<dd>
<p>If you lose any hope, send me this log file so I can eventually
have any clue about the problem / failure.</p>
</dd>
<dd>
<p>Also this is a profiling tool, to know which commands are supported
by your device, so please send me profiles of your devices, so
I can add better support for all devices in the future!</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="todo">TO-DO</a></h1>
<dl>
<dt><strong><a name="item_spooler">Spooler</a></strong>

<dd>
<p>Build a simple spooler program that sends all SMS stored in a special
queue (that could be a simple filesystem folder).</p>
</dd>
</li>
<dt><strong><a name="item_validity_period">Validity Period</a></strong>

<dd>
<p>Support <code>validity</code> period option on SMS sending. Tells how much time the SMS
Service Center must hold the SMS for delivery when not received.</p>
</dd>
</li>
<dt><strong><a name="item_profiles">Profiles</a></strong>

<dd>
<p>Build a profile of the GSM device used, so that we don't have to <code>always</code>
test each command to know whether it is supported or not, because this takes
too time to be done every time.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Cosimo Streppone, <a href="mailto:cosimo@cpan.org">cosimo@cpan.org</a></p>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><a href="/Device/Modem.html">the Device::Modem manpage</a>, <a href="/Device/SerialPort.html">the Device::SerialPort manpage</a>, <a href="/Win32/SerialPort.html">the Win32::SerialPort manpage</a>, <code>perl(1)</code></p>

</body>

</html>
